@growth-labs/cms 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# @growth-labs/cms
+
+The Fronts-proven publishing/admin engine, packaged for reuse. `@growth-labs/cms`
+is a versioned library each site installs and parameterizes with its own
+`D1Database`, R2 media bucket, authz, and theme tokens — **not** a shared runtime
+engine. See [`cms-reuse-decision.md`](../../../olympus-control-plane/docs/reference/cms-reuse-decision.md)
+for the package-not-engine ruling.
+
+> **Status: schema contract + publishing engine + API routes.** This package
+> ships the D1 schema contract and its TypeScript types (the WS7-04/06
+> foundation), the publishing engine — the content data-access core (WS7-05) —
+> **and** the API route handlers (`@growth-labs/cms/routes`, WS7-07): the
+> `/api/v1/publisher/*` content/authors/media/cron surface as framework-agnostic
+> mountable factories with auth/authz **injected**. The admin integration mounts
+> multipart podcast uploads at `/admin/api/media/podcast/{init,part,complete,abort}`.
+
+## What's here
+
+- **The D1 contract** — the 11-table content/revision/media/authors/foundry-callback
+  schema, verified against prod `fronts-data` 2026-05-29:
+  `content_items`, `article_content`, `video_content`, `podcast_content`,
+  `content_revisions`, `content_tags`, `content_tag_links`, `content_relations`,
+  `media_assets`, `authors`, `foundry_callback_events`.
+- **Row types** — a TypeScript interface per table, with the CHECK domains
+  encoded as union types.
+- **Migration helpers** — the SQL as a wrangler-applicable file plus an inlined
+  constant for tests/tooling.
+- **The publishing engine** (WS7-05) — the content data-access core, exported
+  from the package root and the `@growth-labs/cms/engine` subpath: content CRUD
+  + lifecycle (`createContent`, `updateContentItem`, `scheduleContent`,
+  `publishContent`, `unpublishContent`, `duplicateContentItem`), revisions
+  (`createRevision`, `getContentSnapshot`), tags/relations, `ensureUniqueSlug`,
+  `countWords`/`estimateReadTime`, the publish-validation guard, the
+  scheduled-publish sweep (`runScheduledPublish`), the article-body validator,
+  and the content-integrity sanitize passes. Every function takes an **injected
+  `D1Database`** (the site supplies its own binding) — no Fronts coupling.
+
+The contract **excludes** identity/entitlement tables (`users`, `subscription*`,
+`*_entitlements`, `gl_identity_links`, CRM, mailer) and the analytics-owned
+`gl_content_progress`. Those belong to other workstreams — pulling them in is the
+monolith-creep this boundary guards against.
+
+### Intentional schema divergences (do not normalize)
+
+- `media_assets.created_at`/`updated_at` are **TEXT `datetime('now')`**, while the
+  content tables use **INTEGER `unixepoch()`**. This matches prod and the engine
+  code; normalizing it breaks parity.
+- `video_content` uses **`video_id`** (renamed from `stream_uid` in migration
+  0018). Do not reintroduce `stream_uid`.
+- `content_items.type` CHECK includes **`newsletter`** (added in prod 0024).
+
+## Apply the schema
+
+The supported adoption path is wrangler, against the package's `migrations/`:
+
+```bash
+wrangler d1 migrations apply <YOUR_D1_BINDING>
+```
+
+For tests and provisioning tooling without disk access, the same statements are
+available programmatically:
+
+```typescript
+import { applyMigrations, CMS_TABLES } from '@growth-labs/cms/schema'
+
+await applyMigrations(env.SITE_DB) // tests / provisioning only — never request-time
+```
+
+## Use the types
+
+```typescript
+import type { ContentItemRow, MediaAssetRow } from '@growth-labs/cms'
+```
+
+## Use the engine
+
+The engine functions take the site's own `D1Database` as the first argument:
+
+```typescript
+import { createContent, publishContent, runScheduledPublish } from '@growth-labs/cms'
+
+const { id } = await createContent(env.SITE_DB, {
+  type: 'article',
+  slug: 'hello-world',
+  title: 'Hello, world',
+  content: { bodyMarkdown: '# Hello\n\nFirst post.' },
+})
+await publishContent(env.SITE_DB, id, Math.floor(Date.now() / 1000))
+
+// In a scheduled handler:
+await runScheduledPublish(env.SITE_DB)
+```
+
+`primaryCategory` (stored in `content_items.channel`) is site-supplied taxonomy;
+it defaults to `'analysis'` (the Fronts default) when omitted.
+
+### The `duplicateContentItem` column-alignment gotcha
+
+`duplicateContentItem` does four `INSERT…SELECT` copies whose explicit column
+lists are hand-maintained and must stay positionally aligned to the schema.
+`created_at`/`updated_at` are deliberately omitted so the copy gets fresh
+`DEFAULT (unixepoch())` timestamps; the duplicate is forced to `status='draft'`,
+`featured=0`, null publish timestamps/revision, and a video copy is forced to
+`processing_state='ready'` (NOT re-queued to Foundry). **Any future
+`content_items` column addition requires a matching edit in
+`duplicateContentItem` or the duplicate silently drops the new field.**
+
+## Use the routes
+
+The route handlers are framework-agnostic factories at the
+`@growth-labs/cms/routes` subpath. Each handler is a pure
+`(ctx: RouteContext) => Promise<Response>`; the consuming site supplies a thin
+adapter that maps its request + bindings + **its own** authz implementation onto
+a `RouteContext`. The package never decides who is an admin/publisher — it asks
+the injected `authz` guard, so no site's `context.locals.user` / `ADMIN_EMAILS`
+is baked in.
+
+```typescript
+import { createCmsRoutes } from '@growth-labs/cms/routes'
+
+const routes = createCmsRoutes({
+  authz: {
+    requireAdmin: (ctx) => (siteSaysAdmin(ctx) ? null : unauthorized()),
+    requirePublisher: (ctx) => (siteSaysPublisher(ctx) ? null : unauthorized()),
+  },
+  // theme tokens default to the Fronts values when omitted:
+  // mediaPublicDomain: 'media.fronts.co', mediaR2Binding: 'PUBLIC_MEDIA',
+  // mediaSiteId: 'fronts', publishTimezone: 'Europe/Paris', …
+})
+
+// In an Astro route (the site's adapter builds `ctx` from its APIContext):
+export const POST = (c) => routes.content.create(toRouteCtx(c))
+```
+
+The handler groups: `routes.content` (list/create/get/update/action — the
+action endpoint covers schedule/publish/regenerate-takeaways/unpublish/archive/
+unschedule/duplicate), `routes.authors` (list/create/get/update),
+`routes.media` (uploadImage/listLibrary/libraryAction/uploadPodcast plus
+init/part/complete/abort multipart flows for both podcast audio and video
+source uploads), and `routes.cron` (publish — gated by `requireAdmin`).
+
+The article-takeaways **publish** dispatch (Foundry/Hermes) is an OPTIONAL
+injected `dispatchTakeaways` hook on the content config — the package carries no
+Foundry coupling. Omit it and publish simply skips queuing takeaways.
+
+Media transcription dispatch is also injected. When the host supplies the
+Foundry media hook, `dispatch-to-foundry` works for video and podcast content,
+and podcast create/update/publish automatically queues processing when
+`podcast_content.audio_r2_key` is present and the row has neither a
+`processing_trigger_token` nor a transcript. Foundry callbacks matched by
+`processing_trigger_token` update video processing state or, for podcasts,
+persist transcript, duration, description, and excerpt fields when the callback
+payload includes them.
+
+Sites with publish prerequisites can inject `publishReadiness` on the content
+config. The hook receives `{ ctx, contentId, type, status }` before the generic
+publish lifecycle runs. Returning `{ ready: false, blockers, message }` blocks the
+manual publish with a 409 and leaves the content status unchanged; throwing from
+the hook fails closed with a 503. This keeps media-specific readiness checks in
+the host site while preventing a configured site from bypassing them.
+
+## Coming in later waves
+
+- **bead 09 — the admin UI.** `/admin/*` pages via Astro `injectedRoutes` with
+  per-page opt-out, gated on OD-CMS7.

package/dist/engine/activity-log.d.ts

@@ -0,0 +1,17 @@
+import type { D1Database } from './d1.js';
+/** Shape of a single activity log entry (all fields except auto-generated id + created_at). */
+export interface ActivityEntry {
+    workspaceId: string;
+    userId: string | null;
+    action: string;
+    targetId: string | null;
+    targetTitle: string | null;
+    type: string | null;
+}
+/**
+ * Inserts one row into cms_activity_log for the given workspace.
+ * Failures are not thrown — callers should wrap in try/catch if they want to
+ * suppress logging errors (see the publish action pattern).
+ */
+export declare function logActivity(db: D1Database, entry: ActivityEntry): Promise<void>;
+//# sourceMappingURL=activity-log.d.ts.map

package/dist/engine/activity-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-log.d.ts","sourceRoot":"","sources":["../../src/engine/activity-log.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBrF"}

package/dist/engine/activity-log.js

@@ -0,0 +1,17 @@
+// activity-log.ts — first-party D1 write helper for cms_activity_log (P5 Task 3).
+// The table was created in migration 0011. This module provides the single write
+// path (logActivity) so other engine/route code does not inline SQL.
+/**
+ * Inserts one row into cms_activity_log for the given workspace.
+ * Failures are not thrown — callers should wrap in try/catch if they want to
+ * suppress logging errors (see the publish action pattern).
+ */
+export async function logActivity(db, entry) {
+    const id = crypto.randomUUID();
+    await db
+        .prepare(`INSERT INTO cms_activity_log (id, workspace_id, user_id, action, target_id, target_title, type)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .bind(id, entry.workspaceId, entry.userId ?? null, entry.action, entry.targetId ?? null, entry.targetTitle ?? null, entry.type ?? null)
+        .run();
+}
+//# sourceMappingURL=activity-log.js.map

package/dist/engine/activity-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-log.js","sourceRoot":"","sources":["../../src/engine/activity-log.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,iFAAiF;AACjF,qEAAqE;AAcrE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAAc,EAAE,KAAoB;IACrE,MAAM,EAAE,GAAG,MAAM,CAAC,UAAU,EAAE,CAAA;IAC9B,MAAM,EAAE;SACN,OAAO,CACP;iCAC8B,CAC9B;SACA,IAAI,CACJ,EAAE,EACF,KAAK,CAAC,WAAW,EACjB,KAAK,CAAC,MAAM,IAAI,IAAI,EACpB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,QAAQ,IAAI,IAAI,EACtB,KAAK,CAAC,WAAW,IAAI,IAAI,EACzB,KAAK,CAAC,IAAI,IAAI,IAAI,CAClB;SACA,GAAG,EAAE,CAAA;AACR,CAAC"}

package/dist/engine/ai-prompts.d.ts

@@ -0,0 +1,57 @@
+/** House-style system prompt + style guide.
+ *
+ * This is the single shared preamble embedded in every AI prompt. It establishes
+ * the publication's voice, editorial standards, and style constraints so the LLM
+ * produces copy that reads on-brand without fine-tuning or standing RAG infra.
+ *
+ * Exemplar articles, when provided, are passed in-context by the individual
+ * builders — they are NOT stored here.
+ */
+export declare const HOUSE_STYLE_SYSTEM = "You are an expert editor and writer working for a serious, independent digital publication. Your writing is precise, analytical, and authoritative \u2014 you never pad copy with filler phrases or vague hedging.\n\nStyle guide:\n- Voice: clear, direct, and economical. Every sentence earns its place.\n- Tone: serious but not stuffy. Informed but not condescending.\n- Avoid: passive voice where active is possible, clich\u00E9s, jargon without explanation, excessive adjectives, and corporate-speak.\n- Headlines: specific and concrete \u2014 name the actor, the action, and the stakes. Avoid questions and listicles unless they are the strongest option.\n- Meta descriptions: factual summaries that state what the article covers; never a teaser or a question.\n- Takeaways: distil the three most important facts or conclusions; do not repeat the headline.\n- Length discipline: tighter is better. Cut redundant words before adding new ones.";
+/** Input to proofreadPrompt. */
+export interface ProofreadPromptInput {
+    body: string;
+    exemplars?: string[];
+}
+/** Input to headlinesPrompt. */
+export interface HeadlinesPromptInput {
+    title: string;
+    body: string;
+    exemplars?: string[];
+}
+/** Input to takeawaysPrompt. */
+export interface TakeawaysPromptInput {
+    body: string;
+}
+/** Input to metaDescriptionPrompt. */
+export interface MetaDescriptionPromptInput {
+    title: string;
+    body: string;
+}
+/** The typed prompt contract shape consumed by LlmDispatch.dispatch(). */
+export interface AiPromptContract {
+    task: string;
+    prompt: string;
+}
+/**
+ * Build the prompt for "Proofread & tighten".
+ * The LLM should fix grammar and trim approximately 8% of body length,
+ * returning the revised body text.
+ */
+export declare function proofreadPrompt(input: ProofreadPromptInput): AiPromptContract;
+/**
+ * Build the prompt for "Suggest 5 headlines".
+ * The LLM should return exactly 5 SEO-aware headlines, one per line.
+ */
+export declare function headlinesPrompt(input: HeadlinesPromptInput): AiPromptContract;
+/**
+ * Build the prompt for "Generate key takeaways".
+ * The LLM should return 3 bullet takeaways as a JSON array of strings.
+ */
+export declare function takeawaysPrompt(input: TakeawaysPromptInput): AiPromptContract;
+/**
+ * Build the prompt for "Draft meta description".
+ * The LLM should return a single meta description strictly under 160 characters.
+ */
+export declare function metaDescriptionPrompt(input: MetaDescriptionPromptInput): AiPromptContract;
+//# sourceMappingURL=ai-prompts.d.ts.map

package/dist/engine/ai-prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-prompts.d.ts","sourceRoot":"","sources":["../../src/engine/ai-prompts.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,k7BASqD,CAAA;AAEpF,gCAAgC;AAChC,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,gCAAgC;AAChC,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,gCAAgC;AAChC,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,sCAAsC;AACtC,MAAM,WAAW,0BAA0B;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACd;AASD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,gBAAgB,CAS7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,gBAAgB,CAW7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,gBAAgB,CAQ7E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,gBAAgB,CAUzF"}

package/dist/engine/ai-prompts.js

@@ -0,0 +1,90 @@
+// AI prompt contracts for the CMS house-style assist (P4 Task 1).
+// Pure string builders — no I/O, no LlmDispatch call. Every route action
+// calls one of these builders to produce the { task, prompt } pair it hands
+// to LlmDispatch.dispatch().
+/** House-style system prompt + style guide.
+ *
+ * This is the single shared preamble embedded in every AI prompt. It establishes
+ * the publication's voice, editorial standards, and style constraints so the LLM
+ * produces copy that reads on-brand without fine-tuning or standing RAG infra.
+ *
+ * Exemplar articles, when provided, are passed in-context by the individual
+ * builders — they are NOT stored here.
+ */
+export const HOUSE_STYLE_SYSTEM = `You are an expert editor and writer working for a serious, independent digital publication. Your writing is precise, analytical, and authoritative — you never pad copy with filler phrases or vague hedging.
+
+Style guide:
+- Voice: clear, direct, and economical. Every sentence earns its place.
+- Tone: serious but not stuffy. Informed but not condescending.
+- Avoid: passive voice where active is possible, clichés, jargon without explanation, excessive adjectives, and corporate-speak.
+- Headlines: specific and concrete — name the actor, the action, and the stakes. Avoid questions and listicles unless they are the strongest option.
+- Meta descriptions: factual summaries that state what the article covers; never a teaser or a question.
+- Takeaways: distil the three most important facts or conclusions; do not repeat the headline.
+- Length discipline: tighter is better. Cut redundant words before adding new ones.`;
+/** Build the exemplars block when exemplars are supplied. */
+function buildExemplarsBlock(exemplars) {
+    if (!exemplars || exemplars.length === 0)
+        return '';
+    const items = exemplars.map((e, i) => `--- Exemplar ${i + 1} ---\n${e}`).join('\n\n');
+    return `\n\nHere are examples of published articles in this publication's house style for reference:\n\n${items}\n\n--- End of exemplars ---`;
+}
+/**
+ * Build the prompt for "Proofread & tighten".
+ * The LLM should fix grammar and trim approximately 8% of body length,
+ * returning the revised body text.
+ */
+export function proofreadPrompt(input) {
+    const exemplarsBlock = buildExemplarsBlock(input.exemplars);
+    const prompt = `${HOUSE_STYLE_SYSTEM}${exemplarsBlock}
+
+Task: Proofread and tighten the following article body. Fix grammar, punctuation, and style issues. Trim approximately 8% of the length by removing redundant words, padding, and weak phrases — without losing meaning. Return only the revised article body with no commentary or preamble.
+
+Article body:
+${input.body}`;
+    return { task: 'cms.proofread', prompt };
+}
+/**
+ * Build the prompt for "Suggest 5 headlines".
+ * The LLM should return exactly 5 SEO-aware headlines, one per line.
+ */
+export function headlinesPrompt(input) {
+    const exemplarsBlock = buildExemplarsBlock(input.exemplars);
+    const prompt = `${HOUSE_STYLE_SYSTEM}${exemplarsBlock}
+
+Task: Suggest exactly 5 SEO-aware headline alternatives for the following article, in the house voice. Each headline should be specific, concrete, and optimised for search intent. Return exactly 5 headlines, each on a new line, with no numbering, bullets, or additional commentary.
+
+Current title: ${input.title}
+
+Article body:
+${input.body}`;
+    return { task: 'cms.headlines', prompt };
+}
+/**
+ * Build the prompt for "Generate key takeaways".
+ * The LLM should return 3 bullet takeaways as a JSON array of strings.
+ */
+export function takeawaysPrompt(input) {
+    const prompt = `${HOUSE_STYLE_SYSTEM}
+
+Task: Extract exactly 3 key takeaways from the following article. Each takeaway should be a concise, factual sentence that distils an important conclusion or finding. Return ONLY a JSON array of 3 strings — no markdown, no commentary, no preamble. Example output format: ["Takeaway one.", "Takeaway two.", "Takeaway three."]
+
+Article body:
+${input.body}`;
+    return { task: 'cms.takeaways', prompt };
+}
+/**
+ * Build the prompt for "Draft meta description".
+ * The LLM should return a single meta description strictly under 160 characters.
+ */
+export function metaDescriptionPrompt(input) {
+    const prompt = `${HOUSE_STYLE_SYSTEM}
+
+Task: Write a single meta description for the following article. The meta description must be strictly less than 160 characters, factual, and summarise what the article covers. Do not use questions, teasers, or clickbait. Return only the meta description text with no commentary or preamble.
+
+Article title: ${input.title}
+
+Article body:
+${input.body}`;
+    return { task: 'cms.meta', prompt };
+}
+//# sourceMappingURL=ai-prompts.js.map

package/dist/engine/ai-prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-prompts.js","sourceRoot":"","sources":["../../src/engine/ai-prompts.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,yEAAyE;AACzE,4EAA4E;AAC5E,6BAA6B;AAE7B;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;oFASkD,CAAA;AAgCpF,6DAA6D;AAC7D,SAAS,mBAAmB,CAAC,SAA+B;IAC3D,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACnD,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACrF,OAAO,mGAAmG,KAAK,8BAA8B,CAAA;AAC9I,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IAC1D,MAAM,cAAc,GAAG,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IAC3D,MAAM,MAAM,GAAG,GAAG,kBAAkB,GAAG,cAAc;;;;;EAKpD,KAAK,CAAC,IAAI,EAAE,CAAA;IACb,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAA;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IAC1D,MAAM,cAAc,GAAG,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IAC3D,MAAM,MAAM,GAAG,GAAG,kBAAkB,GAAG,cAAc;;;;iBAIrC,KAAK,CAAC,KAAK;;;EAG1B,KAAK,CAAC,IAAI,EAAE,CAAA;IACb,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAA;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IAC1D,MAAM,MAAM,GAAG,GAAG,kBAAkB;;;;;EAKnC,KAAK,CAAC,IAAI,EAAE,CAAA;IACb,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAA;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiC;IACtE,MAAM,MAAM,GAAG,GAAG,kBAAkB;;;;iBAIpB,KAAK,CAAC,KAAK;;;EAG1B,KAAK,CAAC,IAAI,EAAE,CAAA;IACb,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,CAAA;AACpC,CAAC"}

package/dist/engine/ai-writeback.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Parse the raw ai_locked_fields column value (JSON string | null | undefined)
+ * into a string array. Tolerates null, undefined, empty string, and malformed
+ * JSON — returns [] in all error cases.
+ */
+export declare function parseLockedFields(raw: string | null | undefined): string[];
+/**
+ * Return true if the field may be AI-written (not in lockedFields).
+ * Return false if the field is listed in lockedFields.
+ */
+export declare function canWriteField(lockedFields: string[], field: string): boolean;
+/** Input to applyAiWrite. */
+export interface AiWriteInput<T = unknown> {
+    /** The current locked-fields list (from parseLockedFields). */
+    locked: string[];
+    /** The DB column / field name being written. */
+    field: string;
+    /** The AI-generated value to (conditionally) write. */
+    value: T;
+}
+/** Result of applyAiWrite. */
+export interface AiWriteResult<T = unknown> {
+    /** True when the value should be persisted; false when the field is locked. */
+    written: boolean;
+    /** The generated value, echoed back regardless of written status. */
+    value: T;
+}
+/**
+ * Decide whether the AI-generated value for `field` may be persisted.
+ *
+ * - If the field is NOT in `locked` → `{ written: true, value }`.
+ * - If the field IS in `locked` → `{ written: false, value }` (value echoed,
+ *   not written — the caller returns the suggestion but skips the DB update).
+ */
+export declare function applyAiWrite<T = unknown>(input: AiWriteInput<T>): AiWriteResult<T>;
+//# sourceMappingURL=ai-writeback.d.ts.map

package/dist/engine/ai-writeback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-writeback.d.ts","sourceRoot":"","sources":["../../src/engine/ai-writeback.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAS1E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE5E;AAED,6BAA6B;AAC7B,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACxC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,KAAK,EAAE,CAAC,CAAA;CACR;AAED,8BAA8B;AAC9B,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACzC,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAA;IAChB,qEAAqE;IACrE,KAAK,EAAE,CAAC,CAAA;CACR;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAMlF"}

package/dist/engine/ai-writeback.js

@@ -0,0 +1,45 @@
+// ai_locked_fields write-back gate (P4 Task 2).
+// Pure functions — no I/O, no D1, no LlmDispatch.
+//
+// The per-field manual-override model (spec §9): a field listed in
+// ai_locked_fields was hand-edited and must NOT be clobbered by an AI write.
+/**
+ * Parse the raw ai_locked_fields column value (JSON string | null | undefined)
+ * into a string array. Tolerates null, undefined, empty string, and malformed
+ * JSON — returns [] in all error cases.
+ */
+export function parseLockedFields(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Return true if the field may be AI-written (not in lockedFields).
+ * Return false if the field is listed in lockedFields.
+ */
+export function canWriteField(lockedFields, field) {
+    return !lockedFields.includes(field);
+}
+/**
+ * Decide whether the AI-generated value for `field` may be persisted.
+ *
+ * - If the field is NOT in `locked` → `{ written: true, value }`.
+ * - If the field IS in `locked` → `{ written: false, value }` (value echoed,
+ *   not written — the caller returns the suggestion but skips the DB update).
+ */
+export function applyAiWrite(input) {
+    const { locked, field, value } = input;
+    if (canWriteField(locked, field)) {
+        return { written: true, value };
+    }
+    return { written: false, value };
+}
+//# sourceMappingURL=ai-writeback.js.map

package/dist/engine/ai-writeback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-writeback.js","sourceRoot":"","sources":["../../src/engine/ai-writeback.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,kDAAkD;AAClD,EAAE;AACF,mEAAmE;AACnE,6EAA6E;AAE7E;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAA8B;IAC/D,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAA;IACnB,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,CAAA;QACrC,OAAO,MAAkB,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAA;IACV,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,YAAsB,EAAE,KAAa;IAClE,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACrC,CAAC;AAoBD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAc,KAAsB;IAC/D,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;IACtC,IAAI,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;IAChC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC"}

package/dist/engine/api-keys.d.ts

@@ -0,0 +1,76 @@
+import type { D1Database } from './d1.js';
+/** The result of createApiKey — rawKey is revealed ONCE and never stored. */
+export interface CreateApiKeyResult {
+    id: string;
+    /** The full raw key — shown ONCE on creation, never stored in D1. */
+    rawKey: string;
+    /** Safe masked display hint stored in D1 (e.g. 'mk_live_••••ab12'). */
+    masked: string;
+}
+/** A masked API key entry for the list view — no hash, no raw. */
+export interface ApiKeyListEntry {
+    id: string;
+    name: string;
+    /** Safe masked display (e.g. 'mk_live_••••ab12'). */
+    masked: string;
+    scopes: string[];
+    createdAt: number;
+    lastUsed: number | null;
+}
+/** The result of a successful verifyCmsApiKey lookup. */
+export interface VerifyApiKeyResult {
+    workspaceId: string;
+    scopes: string[];
+}
+export interface CreateApiKeyInput {
+    workspaceId: string;
+    name: string;
+    scopes: string[];
+}
+/**
+ * Generate a random API key with the 'mk_live_' prefix.
+ * Uses crypto.getRandomValues for entropy (workerd-native).
+ * The returned value is 32 random bytes encoded as hex (64 chars) + prefix.
+ */
+export declare function generateRawKey(): string;
+/**
+ * Compute the SHA-256 hex digest of a string. Uses Web Crypto (crypto.subtle)
+ * — no node:crypto, workerd-native.
+ */
+export declare function sha256Hex(input: string): Promise<string>;
+/**
+ * Create a new CMS API key.
+ *
+ * - Generates a random raw key (prefix + 32 random hex bytes).
+ * - Computes SHA-256(raw) and stores ONLY the hash.
+ * - Stores a safe masked display hint (key_prefix column, migration 0014).
+ * - Returns the raw key ONCE — it is never retrievable again.
+ */
+export declare function createApiKey(db: D1Database, input: CreateApiKeyInput): Promise<CreateApiKeyResult>;
+/**
+ * List all API keys for a workspace. Returns masked entries — no hash, no raw.
+ * Ordered by created_at ASC (deterministic).
+ */
+export declare function listApiKeys(db: D1Database, workspaceId: string): Promise<ApiKeyListEntry[]>;
+/**
+ * Revoke (delete) an API key by its id, SCOPED to the caller's workspace.
+ *
+ * The workspaceId is resolved from the authenticated caller (auth/locals) and
+ * MUST be passed by the route — never trusted from the client. Scoping the
+ * DELETE by workspace_id closes a cross-workspace IDOR: a member of workspace A
+ * cannot revoke workspace B's key by guessing/leaking its id.
+ *
+ * After revocation, verifyCmsApiKey returns null for the associated raw key.
+ */
+export declare function revokeApiKey(db: D1Database, id: string, workspaceId: string): Promise<void>;
+/**
+ * Verify a raw CMS API key at the content-API gateway.
+ *
+ * - Hashes the raw input via SHA-256.
+ * - Looks up the row by key_hash (equality on the hash — constant-time-safe
+ *   at the DB layer; the raw string is never compared).
+ * - On match: bumps last_used, returns { workspaceId, scopes }.
+ * - On miss (unknown or revoked): returns null.
+ */
+export declare function verifyCmsApiKey(db: D1Database, rawKey: string): Promise<VerifyApiKeyResult | null>;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/engine/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../src/engine/api-keys.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAMzC,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;CACd;AAED,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,EAAE,CAAA;CAChB;AAQD;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAOvC;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D;AAgBD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CACjC,EAAE,EAAE,UAAU,EACd,KAAK,EAAE,iBAAiB,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAiB7B;AAMD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CA2BjG;AAMD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjG;AAMD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACpC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAkBpC"}